/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
/* vim:set et sts=4: */
/* IBust - IBus with Traditional interface
 * Copyright(c) 2013 Daniel Sun
 * Copyright (C) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
 * Copyright (C) 2008-2010 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#if !defined (__IBUST_H_INSIDE__) && !defined (IBUST_COMPILATION)
#error "Only <ibust.h> can be included directly"
#endif

/**
 * SECTION: ibustlookuptable
 * @short_description: Candidate word/phrase lookup table.
 * @stability: Stable
 * @see_also: #IBustEngine
 *
 * An IBustLookuptable stores the candidate words or phrases for users to choose from.
 *
 * Use ibust_engine_update_lookup_table(), ibust_engine_show_lookup_table(),
 * and ibust_engine_hide_lookup_table() to update, show and hide the lookup
 * table.
 */
#ifndef __IBUST_LOOKUP_TABLE_H_
#define __IBUST_LOOKUP_TABLE_H_

#include "ibustserializable.h"
#include "ibusttext.h"

/*
 * Type macros.
 */
/* define IBustLookupTable macros */
#define IBUST_TYPE_LOOKUP_TABLE             \
    (ibust_lookup_table_get_type ())
#define IBUST_LOOKUP_TABLE(obj)             \
    (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUST_TYPE_LOOKUP_TABLE, IBustLookupTable))
#define IBUST_LOOKUP_TABLE_CLASS(klass)     \
    (G_TYPE_CHECK_CLASS_CAST ((klass), IBUST_TYPE_LOOKUP_TABLE, IBustLookupTableClass))
#define IBUST_IS_LOOKUP_TABLE(obj)          \
    (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUST_TYPE_LOOKUP_TABLE))
#define IBUST_IS_LOOKUP_TABLE_CLASS(klass)  \
    (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUST_TYPE_LOOKUP_TABLE))
#define IBUST_LOOKUP_TABLE_GET_CLASS(obj)   \
    (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUST_TYPE_LOOKUP_TABLE, IBustLookupTableClass))


G_BEGIN_DECLS

typedef struct _IBustLookupTable IBustLookupTable;
typedef struct _IBustLookupTableClass IBustLookupTableClass;

/**
 * IBustLookupTable:
 * @page_size: number of candidate shown per page.
 * @cursor_pos: position index of cursor.
 * @cursor_visible: whether the cursor is visible.
 * @round: TRUE for lookup table wrap around.
 * @orientation: orientation of the table.
 * @candidates: Candidate words/phrases.
 * @labels: Candidate labels which identify individual candidates in the same page. Default is 1, 2, 3, 4 ...
 *
 * An IBustLookuptable stores the candidate words or phrases for users to choose from.
 * Note that some input methods allow you to select candidate by pressing non-numeric
 * keys such as "asdfghjkl;".
 * Developers of these input methods should change the labels with
 * ibust_lookup_table_append_label().
 */
struct _IBustLookupTable {
    IBustSerializable parent;

    /*< public >*/
    guint page_size;
    guint cursor_pos;
    gboolean cursor_visible;
    gboolean round;
    gint orientation;

    GArray *candidates;
    GArray *labels;
};

struct _IBustLookupTableClass {
    IBustSerializableClass parent;
};


GType                ibust_lookup_table_get_type (void);

/**
 * ibust_lookup_table_new:
 * @page_size: number of candidate shown per page, the max value is 16.
 * @cursor_pos: position index of cursor.
 * @cursor_visible: whether the cursor is visible.
 * @round: TRUE for lookup table wrap around.
 * @returns: A newly allocated IBustLookupTable.
 *
 * New a IBustLookupTable.
 */
IBustLookupTable     *ibust_lookup_table_new      (guint               page_size,
                                                 guint               cursor_pos,
                                                 gboolean            cursor_visible,
                                                 gboolean            round);

/**
 * ibust_lookup_table_append_candidate:
 * @table: An IBustLookupTable.
 * @text: candidate word/phrase to be appended (in IBustText format).
 *
 * Append a candidate word/phrase to IBustLookupTable, and increase reference.
 */
void                 ibust_lookup_table_append_candidate
                                                (IBustLookupTable    *table,
                                                 IBustText           *text);

/**
 * ibust_lookup_table_get_number_of_candidates:
 * @table: An IBustLookupTable.
 * @returns: The number of candidates in the table
 *
 * Return the number of candidate in the table.
 */
guint               ibust_lookup_table_get_number_of_candidates
                                                (IBustLookupTable    *table);

/**
 * ibust_lookup_table_get_candidate:
 * @table: An IBustLookupTable.
 * @index: Index in the Lookup table.
 * @returns: (transfer none): IBustText at the given index; NULL if no such IBustText.
 *
 * Return IBustText at the given index. Borrowed reference.
 */
IBustText            *ibust_lookup_table_get_candidate
                                                (IBustLookupTable    *table,
                                                 guint               index);

/**
 * ibust_lookup_table_append_label:
 * @table: An IBustLookupTable.
 * @text: A candidate label to be appended (in IBustText format).
 *
 * Append a candidate word/phrase to IBustLookupTable, and increase reference.
 * This function is needed if the input method select candidate with
 * non-numeric keys such as "asdfghjkl;".
 */
void                 ibust_lookup_table_append_label
                                                (IBustLookupTable    *table,
                                                 IBustText           *text);

/**
 * ibust_lookup_table_set_label:
 * @table: An IBustLookupTable.
 * @index: Intex in the Lookup table.
 * @text: A candidate label to be appended (in IBustText format).
 *
 * Append a candidate word/phrase to IBustLookupTable, and increase reference.
 * This function is needed if the input method select candidate with
 * non-numeric keys such as "asdfghjkl;".
 */
void                 ibust_lookup_table_set_label
                                                (IBustLookupTable    *table,
                                                 guint               index,
                                                 IBustText           *text);

/**
 * ibust_lookup_table_get_label:
 * @table: An IBustLookupTable.
 * @index: Index in the Lookup table.
 * @returns: (transfer none): IBustText at the given index; NULL if no such IBustText.
 *
 * Return IBustText at the given index. Borrowed reference.
 */
IBustText            *ibust_lookup_table_get_label
                                                (IBustLookupTable    *table,
                                                 guint               index);


/**
 * ibust_lookup_table_set_cursor_pos:
 * @table: An IBustLookupTable.
 * @cursor_pos: The position of cursor.
 *
 * Set the cursor position of IBustLookupTable.
 */
void                 ibust_lookup_table_set_cursor_pos
                                                (IBustLookupTable    *table,
                                                 guint               cursor_pos);

/**
 * ibust_lookup_table_get_cursor_pos:
 * @table: An IBustLookupTable.
 * @returns: The position of cursor.
 *
 * Get the cursor position of IBustLookupTable.
 */
guint                ibust_lookup_table_get_cursor_pos
                                                (IBustLookupTable    *table);

/**
 * ibust_lookup_table_set_cursor_visible:
 * @table: An IBustLookupTable.
 * @visible: Whether to make the cursor of @table visible.
 *
 * Set whether to make the cursor of an IBustLookupTable visible or not.
 */
void                 ibust_lookup_table_set_cursor_visible
                                                (IBustLookupTable    *table,
                                                 gboolean            visible);

/**
 * ibust_lookup_table_is_cursor_visible:
 * @table: An IBustLookupTable.
 * @returns: Whether the cursor of @table is visible.
 *
 * Returns whether the cursor of an IBustLookupTable is visible.
 */
gboolean             ibust_lookup_table_is_cursor_visible
                                                (IBustLookupTable    *table);

/**
 * ibust_lookup_table_get_cursor_in_page:
 * @table: An IBustLookupTable.
 * @returns: The position of cursor in current page.
 *
 * Get the cursor position in current page of IBustLookupTable.
 */
guint                ibust_lookup_table_get_cursor_in_page
                                                (IBustLookupTable    *table);

/**
 * ibust_lookup_table_set_page_size:
 * @table: An IBustLookupTable.
 * @page_size: number of candidate shown per page.
 *
 * Set the number of candidate shown per page.
 */
void                 ibust_lookup_table_set_page_size
                                                (IBustLookupTable    *table,
                                                 guint               page_size);
/**
 * ibust_lookup_table_get_page_size:
 * @table: An IBustLookupTable.
 * @returns: Page size, i.e., number of candidate shown per page.
 *
 * Get the number of candidate shown per page.
 */
guint                ibust_lookup_table_get_page_size
                                                (IBustLookupTable    *table);

/**
 * ibust_lookup_table_set_round:
 * @table: An IBustLookupTable.
 * @round: Whether to make @table round.
 *
 * Set whether to make the IBustLookupTable round or not.
 */
void                 ibust_lookup_table_set_round
                                                (IBustLookupTable    *table,
                                                 gboolean            round);
/**
 * ibust_lookup_table_is_round:
 * @table: An IBustLookupTable.
 * @returns: Whether the @table is round.
 *
 * Returns whether the IBustLookupTable is round.
 */
gboolean             ibust_lookup_table_is_round (IBustLookupTable    *table);

/**
 * ibust_lookup_table_set_orientation:
 * @table: An IBustLookupTable.
 * @orientation: .
 *
 * Set the orientation.
 */
void                 ibust_lookup_table_set_orientation
                                                (IBustLookupTable    *table,
                                                 gint                orientation);

/**
 * ibust_lookup_table_get_orientation:
 * @table: An IBustLookupTable.
 * @returns: The orientation of the @table.
 *
 * Returns the orientation of the IBustLookupTable.
 */
gint                 ibust_lookup_table_get_orientation
                                                (IBustLookupTable    *table);


/**
 * ibust_lookup_table_clear:
 * @table: An IBustLookupTable.
 *
 * Clear and remove all candidate from an IBustLookupTable.
 */
void                 ibust_lookup_table_clear    (IBustLookupTable    *table);

/**
 * ibust_lookup_table_page_up:
 * @table: An IBustLookupTable.
 * @returns: TRUE if succeed.
 *
 * Go to previous page of an IBustLookupTable.
 *
 * It returns FALSE if it is already at the first page,
 * unless  <code>table&gt;-round==TRUE</code>, where it will go
 * to the last page.
 */
gboolean             ibust_lookup_table_page_up  (IBustLookupTable    *table);

/**
 * ibust_lookup_table_page_down:
 * @table: An IBustLookupTable.
 * @returns: TRUE if succeed.
 *
 * Go to next page of an IBustLookupTable.
 *
 * It returns FALSE if it is already at the last page,
 * unless  <code>table&gt;-round==TRUE</code>, where it will go
 * to the first page.
 */
gboolean             ibust_lookup_table_page_down(IBustLookupTable    *table);

/**
 * ibust_lookup_table_cursor_up:
 * @table: An IBustLookupTable.
 * @returns: TRUE if succeed.
 *
 * Go to previous candidate of an IBustLookupTable.
 *
 * It returns FALSE if it is already at the first candidate,
 * unless  <code>table&gt;-round==TRUE</code>, where it will go
 * to the last candidate.
 */
gboolean             ibust_lookup_table_cursor_up(IBustLookupTable    *table);

/**
 * ibust_lookup_table_cursor_down:
 * @table: An IBustLookupTable.
 * @returns: TRUE if succeed.
 *
 * Go to next candidate of an IBustLookupTable.
 *
 * It returns FALSE if it is already at the last candidate,
 * unless  <code>table&gt;-round==TRUE</code>, where it will go
 * to the first candidate.
 */
gboolean             ibust_lookup_table_cursor_down
                                                (IBustLookupTable    *table);
G_END_DECLS
#endif

